Workbench Design/WB Collection.iso/workbench werkzeuge/appicon tools/rubbishdump/upd/upd.doc

Text File | 1996-04-07 | 17KB | 447 lines

Release 1.40

        The minimal player daemon - upd
        ===============================

   © 1991-1994 Jonas Petersson & Absolut Software (aka Sirius Soft)



Introduction:
=============

Wouldn't it be nice to have a process hanging around to play any
sound file for you on demand instead of you having to do all this
mucking about with audio.device etc? But it really has to be small
and it HAS to be able to play my very large samples anytime...
I must be able to call it simply from anywhere - even from scripts!

Tricky, but it can be done.

As a feature you can register you favourite sounds in a configuration
file and well behaved programs will use the ones you like right now.
It also has Arexx support - to be truely honest, that the ONLY way to
use it... As of 1.01, there is also a fade option.

Actually, "minimal" is not quite true anymore as speech is available
starting 1.20... As a spin-off of this you also get a "say" program
that can play phonemes.

1.30 includes a way to preload the samples from disk.

1.40 includes a way to register several IDs to be played at random and
the ability to play every request to the end (disable the lookahead
feature).

Current version works rather well along the way I intended.


Changes:
========

Option -Q turns on Queue mode where every single request is played
to the end no matter how much is queued up. You have been warned.
Specifying a FADE of "-1" gives the same result - obviously queue
and fade are mutually exclusive.

If you register the same ID several times in the ID file (normally
s:UPD.IDs) UPD will pick one of them at random.


Usage:
======

    [run] upd [-bBUFSIZE] [-fIDFILE] [-pPRIORITY] [-M] [-Q]

The "run" is of course optional, but daemons really should be in the
background unless you want the see the debugging information.  "BUFSIZE"
is the amount of chip memory that each of the four buffers will use
while playing.  (These are allocated at start to make sure you will be
able to play anytime - as long as you can get hold of the audio
channels...).  Default is 1024 and specifying less than 64 will give you
the default. (I've heard that some people can't ever get anything good
out with less than a 1K buffer - am I really the only one with a quick
enough HD/SCSI interface?)

NOTE: Don't make the buffer bigger than you actually need - a large
buffer also means that the sample will start a little bit later since
more information must be loaded before it can begin!

If the IDfile parameter exists, it will be used instead of the
default s:upd.IDs.

As of 1.20 I've also added the priority option to satisfy some requests
from people who prefer their sound to be perfect before getting things
done... You people may specify -p35 or something like that along with
some huge buffer. Of course, you can also lower priority with this option.

As of 1.30, the -M option can be used to waste your RAM! If present at
startup, upd will always try to find a memory space to load the sample
into before playing it. If that fails the sample will play from disk
as before. This will of course delay the sound a bit as well. For small
samples there is hardly any difference, for medium size samples there
is a delay but no access to the disk while playing, and for large samples
things are just like before. (I don't use this option myself...)

As of 1.40, the -Q option turns om Queue mode from the start.

The above won't produce any sound as you probably realise.  Once run, the
only way to talk to upd is with Arexx - I even removed the BREAK stuff
that was in it for Zound, since Arexx could hang around waiting for a
reply forever when you interupted the sound that way. The break will
"wait" until the daemon is idle next time.

upd currently knows of these commands:

    file filepath [options] [anotherfilepath [options]]
    id   id-in-s:upd.IDs
        rescan new-id-file
    fade #-of-steps-per-bufsize
    say string-to-translate-and-say
    phoneme phoneme-string-to-say
    exit

The 'fade' command is new to 1.01 and might need some explanation:
What is does is merely reconfigure upd for future requests. By default
fade is set to 0 which means that any playing sound will be cut off
as soon as a new AREXX command arrives. Any other number indicates that
when a new request arrives, first fade out the current sound by lowering
the volume by the specified amount by each played buffer until volume reaches
zero. As the observant reader realises, a value exceeding 64 will do
the same thing as 0. As of 1.40 a negative value will put UPD in Queue mode.

'say' and 'phoneme' are new as of 1.20 and their use should be obvious.
These are really just a spin-off from what was added to the ID file.
Speech currently won't fade - I fail to see the beauty in fading it...
NOTE: You must have LIBS:translator.library and DEVS:narrator.device on
your system of this will NOT work.

Well, there is actually one more command: 'Can it, Marvin'. This will
silently interrupt the current sample. (To be truely honest, ANY command
will interrupt a sample - if it's known, it will be used, otherwise the
sound just stops). Note: this does NOT work in Queue mode.

Be careful with the 'rescan' command: if there is a problem reading the
new file, you will have no IDs at all...

The options are the same as for Zound except for the -n option that doesn't
exist here (tell me you need it and I'll fix that too... sigh). Here's the
list:

    -r rate    How fast to play the sample. Default is what is in the
        8SVX header or 310 if it's a raw file. This is usually
        reasonable - most 'raw' samples I've come across are either
        310 or 155. Lower numbers will play the sample faster.

    -v volume    Ranges between 0 and 64, 64 being max and default.

    -s start    Possible offset from the beginning. Default 0.

    -l length    Possible length unless you want it all. Default is
        length of the sample. Be careful with these two, or
        you might get undesired results.

    -c cycles    How many times to play each buffer. Default 1. Not
        very useful, but you can get a nice "mouse" effect by
        setting this to 2 and playing twice as fast...

    -d        Toggle debug information. Note that this will appear on
        the standard output of the DAEMON, not where you called
        it from (that is, the ARexx script or wherever).

    -L        Play the sample in the left speaker only. If it's a stereo
        sample only the left channel samples are used.
    -R        Same as '-L' but for right speaker.
    -S        Play in both speakers even if it's a mono sample.
        Default for these three options are of course what is in the
        8SVX header or -L if it's a raw sample.

Examples:
=========

* Example of usage (from WShell etc):

    "address play file 'sounds:chopper'
    "address play fade 2
    "address play id 2001
        "address play rescan 'ram:upd.IDs'
    "address play exit


* If you are using the vanilla 2.0 AREXX you might have to create a file
  like this:

    /* A test script in AREXX */

    address PLAY say "Hi there!"

  Then execute it with 'rx filename.rexx'

  Alternatively, you can give a command like this (note the tick [']):

    rx 'address PLAY say "Hi there!"


* Say "emulations":

    address play say "-f -r -s100 E T phone home."
    address play phoneme "-s200 YUWNAEZ PEH1TERSUN"


NOTE: Arexx normally converts everything to UPPERCASE and might try to
do arithmetics etc on filenames which is why it's generally a good idea
to 'singelquote' all paths, IDs etc. If you're looking for the port
'the hard way' to send your own message, the name is "PLAY" in uppercase.

NOTE2: If you are REALLY in a hurry to get rid of upd you could do this:
 1) Send a any dummy Arexx message (this will stop the sound)
 2) Send a break C to upd - break still works when upd is idle.
or
 A) Send the exit message.

The last might sound much easier than the first unless you (like me)
have a trapped DisplayBeep() that 'pings' via upd.  In this case,
producing a DisplayBeep() and a break C is much simpler.  The order is
not relevant since the break is "queued".


Hints:
======

Running upd from your SOUNDS: directory is a nice way to get rid of having
you type the FULL path everytime you want to play a sample. (The daemon
has no simple way of knowing WHERE you were when you sent the message
(that I know of) and therefore assumes it to be in the current directory)


Files:
======

    s:upd.IDs

This file contains the IDs of your favourite samples like a database
the is easily editable. File format:


# Lines starting with '#' are comments
# Id list for micro player daemon
# Created 910201 Jonas Petersson ([e-mail])
# These sounds could be called for at certain situations
# On severe error
BUG    sounds:explosion -S
# When asked for confirmation
CONFIRM sounds:PressLeftMouseButton -L
# Minor trouble
ERROR   sounds:ImSorryDaveImAfraidICantDoThat -R
# Going down...
GURU    sounds:RoysDeathMonologueFromBladerunner -S
# Personal shortcuts/favourites
2001    sounds:openpod -L sounds:hal -R
# These should always work:
ET      -SAY -r -f -p100 -F20000 -s110 E T phone home.
AUTHOR  -PHONEME YUWNAEZ PEH1TERSUN
# These are for Arq
warn_write_protected    -SAY I'm afraid I can't do that.
warn_insert_volume      -SAY I can't see it.
warn_delete             -SAY Oh no.
warn_printer            -SAY Printer trouble.
error_task_held         -SAY You are in deep shit.
error_read_write        -SAY Bad disk.
error_general           -SAY Error.
warn_general            -SAY Warning.
query_general           -SAY Please.
# UPD will select one of the following at random.
beep                    -SAY Beep.
beep                    -SAY Ouch.


-SAY and -PHONEME are special "files" as of 1.20. These instead trigger
the use of translator/narrator since some people don't have a lot of
samples around. Remember that everything is different here - options
come BEFORE the string and have other meanings than for samples. I've
tried to keep the the same as the command 'say' uses:

    -m/-f    Male/Female
    -n/-r    Natural/Robot
    -p###    Pitch
    -v###    Volume
    -s###    Speed (rate really)
    -F###    Sample frequency

    (Defaults are the same as for "say")

For duplicate entries, one of them will be selected at random.

Removing entries will of course result in no sound (upd might mourn about
it on the standard output though, unless you redirect it). Remember that
ARexx might convert to uppercase unless you quote!

Feel free to add whatever you like. Could be nice with some standard though.
If you make a program that uses several ID's it would be a good idea to have
the same prefix for instance.

Suggestions are welcome. Mjl's Arq is an example of a program that uses
this feature. Read Arq's docs for details. Another example program that
uses upd is ToolManager by Stefan Becker.

NOTE: It *IS* possible to have white space, lowercase etc in the IDs, but
it might cause confusion if used. Be warned.

NOTE2: The file is scanned once when the program starts. If you make any
changes to it, you'll have to restart the deamon or ask it to scan the file
explicitly.


Return codes:
=============

If the Arexx command returns 20, the secondary result code gives the
reason for the failure:

10    Can't allocate channels.
17    Can't open s:upd.IDs on request to play by ID.
18    Requested ID not found.
19    Trouble reading new ID file.
20    Error during parse of options.
21    Can't open file with sample.
22    File is IFF, but not FORM 8SVX.
23    Bad IFF file.
24    Bad CHAN length.
25    Bad VHDR length.
26    Can't open file 2nd time. (For stereo possibility)
30    Can't play backwards. (Weird options)
31    Can't allocate IOAudio structs.
32    Can't open ports for channels.
47    Can't open the translator library.
48    Translator won't use that string.
50    Bad options to -SAY/-PHONEME in ID line.
51    Can't open the narrator device.
52    Couldn't Allocate talk Signal bit.
53    Narrator won't do that. Usually bad pitch etc.



Being interrupted to do something else is not considered a failure. Note
that this is true even if the current message has not been parsed yet.
That is if UPD is sent these two messages (in order):

    address PLAY phoneme "Hi there!"
    address PLAY say "Hi there!"

It will not parse the first one since it knows there is another one
waiting and therefore returns 0 (OK) for the first even though it
contains invalid phonemes. This should hardly be a problem and you
hardly want it to work the other way since that might slow down things
significantly when you have a lot of queued requests (likely when trapping
DisplayBeep() for instance). [Note that putting the above two messages
after each other in a script WONT send them at the same time since upd
doesn't release the first message until it's done!]


Future enhancements:
====================

Maybe automatic detach (Doesn't work well in Aztec 5.0d).

Probably not very much else - this is a simple sound daemon for minor
background purposes of helping simple programs do more than DisplayBeep().
I'd like to think of it as a complement to SPEAK: - if you want more
you probably want it interactive. (Hmm, that's a thought - a SOUND: device)



Problem history:
================

1. If your sample is on a floppy (or a very slow HD) there might be
   some sounds of silence when the playing rate exceeds the loading
   rate...
Fix: You can now specify the amount of memory to be used by upd when you
   start the daemon as in: 'upd -b2000'. But note that a larger buffer also
   makes a longer delay until you hear the first part of the sound - it
   doesn't start until it has filled the first buffer.

2. Stereo and Fibonachi packed samples not yet supported (there are loading
   problems - play them with 'Zound' instead for now).
Fix: Stereo is OK now if you use the above size option (it actually worked
   in RAM: before too - but I didn't enable it for the prerelease). As for
   Fibonachi: it's not too hard to fix, but I've never seen anyone using it -
   is it worth the effort? If you happen to have a Fib-sample - PLEASE send it
   to me - I don't have the patience to reconstruct one by hand...

3. Could hang forever if someone stole the channel.
Fix: So, I didn't check everything in 0.99 - now I do (I hope... ;-)

4. -s and -l weren't used in 0.99, now they are.

5. On request from the UK CDTV developers, FADE was added as of 1.01

6. On request from various people, added option -p## at startup to make
it simpler to raise priority for those demanding perfect sound but are
to lazy to use "ChangeTaskPri" for it...

7. Added speech and better command line parsing as of 1.20.

8. Options to say and phoneme DID work with 1.20, but a lot of people
   got hold of the prerelease where it didn't work! 1.25 is a safe version.

9. Up until v1.25 there was a harmless Enforcer hit at address 0 due to
   sloppy command line parsing.

10. Due to the v1.20 prerelese confusion, there is now a version string!

11. Due to some very stubborn users, there is from 1.30 an option '-M'
for Memorywaste. If there is a big enough chunk of memory, the sample
is read into it before playing is started.

12. Some other very stubborn users demanded a "Queue" which in reality
disables all the work I've put in to abort a sound because another request
is coming in... 1.40

13. Random ID playing added as of 1.40.

Thanks to [e-mail] for the idea.


Distribution
============

  UPD is not public domain. A friend of mine advised me to call it
"Freely Distributable Copyrighted" instead. That's close enough.
If you wish to include it with a commercial program feel free provided
that you send me a registered copy. And don't forget to mention me
in the manual.

  An additional request to developers who add support for UPD: Please
let me know of it - people tend to ask ME why your program fails to
work with UPD...

  As always, Fred Fish is free to include it in his library.

  Source code? You mean there is something to IMPROVE??? Right, send
me a message then and I'll think about it...





    Jonas 'Zaphod' Petersson    NOTE: New address!
    Kneippgatan 3
    S-602 36  Norrkoping
    SWEDEN
    Voice: [phone]    Remember: I'm in Sweden - Timezone GMT+1!
    Modem: [phone]        magrathea (A1000) will let you leave
                    a message for me if you log in as "guest".

    [e-mail]                   /* At home */
    [e-mail]                    /* At work  - Quickest */


Feel free to send comments, bug reports (huh?), money, coke, beer...
[Sorry, girls are no longer allowed as I'm married now!]

Just a "Hi, I liked your program" is as good as a few bucks - I wrote this
because I needed it, not to make money out of it...